=======================
= TinyELF README FILE =
=======================

TinyELF is an emulator of 1802-based microcomputers that runs on Palm OS handhelds.

The RCA CDP1802 microprocessor was the basis for a number of small computers in the mid-70s through the early eighties. The original ELF was described in an August 1976 Popular Electronics article by Joseph Weisbecker, who later expanded the machine with more memory, a hexadecimal keypad and primitive video output. Several commercial companies soon followed with 1802-based computers of their own.

More on the history of 1802-based computing may be found at http://www.cosmacelf.com and many of the links found on that site.


================
= INSTALLATION =
================

HotSync the TinyELF.prc file to your Palm OS handheld. You may also install elfprog-1802.pdb for some sample ELF programs, but note that if this file already exists on your handheld doing so will overwrite existing TinyELF programs.

Mac OS X users may wish to check the TinyELF page on http://www.cosmacelf.com for an application that allows easy import and export of 1802 programs. Other versions may also be made available in the future.


===================
= BASIC OPERATION =
===================

The original ELF used eight toggle switches for input data; the Netronics ELF II used a hexadecimal keypad. Both used toggle switches for controlling the microprocessor's mode (the Load and Run toggles) and write access to memory (the M/P toggle). TinyELF emulates both panel layouts as user-selectable "skins"; to switch between them, bring up the Preferences dialog from the Option menu. You can also select the amount of RAM you'd like to equip TinyELF with. Note that on older handhelds larger memory sizes may not work, in which case TinyELF will revert to 256 bytes of memory.

All toggle switches are "on" when up, "off" when down.

The 1802's four modes are controlled as follows:

RESET MODE (Run off, Load off) - Resetting the 1802 clears R(0), P, X and Q.

LOAD MODE (Run off, Load on) - This mode allows data to be manually loaded into TinyELF's memory. When the IN (or "I") button is pressed, the data buffered from either the toggle switches or the hex keypad is loaded into the memory pointed to by R(0), then R(0) is incremented. Note that if Load mode is entered from Reset mode, data entry begins at address 0000 since R(0) is cleared.

RUN MODE (Run on, Load off) - Putting TinyELF in Run mode executes the program in memory. If entered from Reset mode, execution begins at 0000, since P is cleared (making R(0) the program counter) and R(0) is also cleared.

PAUSE MODE (Run on, Load on) - Transitioning to Pause mode halts program execution but does not clear registers.

A memory protect switch ("M/P") prevents memory writes when on. This can be used in conjunction with the Load switch to sequentially examine memory contents: each press of the IN (or "I") button will display the byte at R(0), after which R(0) will be incremented.


==========
= WIRING =
==========

Like Weisbecker's ELF and the Netronics ELF II, TinyELF features a hexadecimal display for data output. This is wired to output port 4 of the 1802, allowing an OUT4 opcode to change the display while running. A single LED is also wired to the 1802's Q output line; the SEQ (set Q) and REQ (reset Q) opcodes change the state of this output.

The 8 toggle switches or hexadecimal keypad are wired to input port 4; an IN4 opcode will read the current value. The IN (or "I") button is wired to EF4, one of the 1802's four "external flag" lines. The state of the IN button may be determined by using the 1802's B4 (branch if EF4) and BN4 (branch if not EF4) instructions.

Version 1.10 of TinyELF adds support for an ASCII keyboard, wired as though it were on the 1802's parallel port... or, rather, on several of them. Because configurations of 1802-based computers varied from one hacker to the next, and because there's really nothing else one can hook up to TinyELF, characters get input to ports 2, 3, 5, 6, and 7, with both EF2 and EF3 momentarily activated as a strobe for each character. As a result, most 1802 programs using a parallel ASCII keyboard should work with TinyELF. To input ASCII characters with Grafitti or the Palm Portable keyboard, be sure to set the Grafitti option in TinyELF's Preferences to "ASCII"; otherwise, Grafitti or the keyboard will input hexadecimal characters as though you were pushing buttons on the hex pad.


=======================
= 1861 PIXIE GRAPHICS =
=======================

TinyELF also emulates the 1861 "Pixie" graphics chip. This chip is tied to the 1802 through its interrupt line, its DMA out channel, EF1, and the 1802's N0 line.

The 1861 is turned on by the N0 line, or the low bit of the three lines used to decode an I/O access. In practice, this means that an IN or OUT to any odd-numbered port will turn on the graphics chip. Usually ELF programs used an IN1 opcode for this purpose.

RCA's documentation for the 1861 shows a sample implementation that allows the chip to be turned off with the 1802's N1 line, but this is not how the original ELF or the Netronics ELF II wired the circuit. Instead, the 1861 remained on until the Run toggle was switched off.

Once turned on, a real 1861 interrupts the 1802 60 times per second, once per frame. Each frame is composed of 262 lines. When clocked at a frequency of approximately 1.76 MHz, each line will take 14 machine cycles.

Four lines prior to the first line the 1802 will paint, EF1 is raised. Two lines prior, the interrupt from the 1861 comes in, giving the 1802 exactly 29 cycles before the first DMA request. During that time, the 1802 is expected to save registers used by the interrupt service routine and set up R(0) (the DMA pointer) to point to the first byte to be displayed. Eight DMA out cycles will occur, fetching eight consecutive bytes from memory pointed to by R(0), R(0) getting incremented after each cycle. The 1802 has time for six cycles (three two-cycle instructions, for example) before the next 8 DMA cycles. EF1 is again raised during the last four lines of the 1861's display frame.

Each byte fetched by DMA is displayed sequentially on a raster line, giving a horizontal resolution of 64 bits. The 1861 paints a total of 128 lines, but by manipulating R(0) during interrupt service lower vertical resolutions can be simulated. A full resolution display of 64 pixels across by 128 pixels down requires 1024 bytes of memory. By repeating each line four times, however, the display will appear to be 64 pixels across by 32 pixels down, showing a total of 256 bytes of memory on-screen.


================
= HELLO, WORLD =
================

The ELF equivalent of the minimal "Hello, World" program is two bytes long: it turns on the Q LED and halts. To enter this program, first reset TinyELF by putting switching off the Run and Load toggles. Make sure the memory protect ("M/P") switch is off as well so that bytes can be entered into memory.

Now flip the Load toggle back on. Using the data toggle switches or the hex keypad, enter the byte 0x7B and press the IN key. The hexadecimal display should show "7b." Opcode 0x7B is the 1802's SEQ instruction, which turns on the Q line and the LED. Now enter the byte 0x00 and press the IN key again to store an IDL (idle) opcode in memory location 0x0001. Flip the Load switch back off, resetting the 1802.

Now flip the Run switch on; the Q LED should light. Congratulations, you've entered and run the world's simplest TinyELF program!


=============================
= ABOUT THE SAMPLE PROGRAMS =
=============================

TinyELF comes with several sample programs in its database (elfprog-1802.pdb). To run these, reset TinyELF (put both the Run and Load toggles in the down position), turn off the memory protect (M/P) toggle, and select the "Load" option from TinyELF's Program menu. Choose the program and tap the OK button, then flip the Run toggle switch on.

- Output Test (18 bytes) - continuously increments the hex display and blinks the Q LED. Can you figure out how it works?

- Starship Classic (256 bytes) - uses Pixie graphics to display the starship graphic from the Popular Electronics article on adding video support to an ELF computer.

- Seconds Clock (256 bytes) - this program displays a seconds counter using Pixie graphics, and was written by Tom Pittman for his "Short Course in Programming." This excellent tutorial on the ELF computer and the 1802 instruction set may be found at http://www.cosmacelf.com. The program is modified to run quicker on TinyELF (a constant was changed), but don't set your watch by it!

- Kaleidoscope (768 bytes) - make sure you've selected either 4K or 16K of memory in TinyELF's preferences to run this one. V. G. Cayer contributed this program to the Ipso Facto newsletter back in the early 80s. It creates symmetrical patterns using Pixie graphics.

- Starship Animation (256 bytes) - another program from the Popular Electronics article, this one moves the starship across the screen from left to right. To get it moving, run the program and input a value (try 0xFF) using the hex keys or the toggle switches, then press the input button.

- Seconds Clock on Hex Display (52 bytes) - this will give you an idea how much slower TinyELF is than a real ELF computer. A real ELF, running at about 1.79 MHz, increments the count about once per second. On TinyELF, the display WILL increment... but be patient!

- Q Toggle (12 bytes) - this small and simple program toggles the Q LED with alternate presses of the input button. Figuring out this program is a great project for beginners!

- ASCII Keyboard Test (15 bytes) - be sure to select "ASCII" for the Grafitti option in TinyELF's preferences. As characters are entered in either Grafitti or on an attached Palm Portable Keyboard, their value in hexadecimal is displayed on the hex LEDs.

- Tiny BASIC (4096 bytes) - Tom Pittman created this clever BASIC interpreter, complete with Pixie graphic output with proportionally spaced characters. The interpreter, video, and even the ASCII dot table occupy a mere 4K --- much smaller than this ReadMe.txt file! Rather slow even on a real ELF, it CRAWLS on TinyELF. Select the "ASCII" Grafitti option in TinyELF's preferences. After turning on the Run toggle, enter a carriage return using either Grafitti or the Palm Portable Keyboard. After about 2 minutes, Pixie graphics should kick in; about half a minute later, you should see a colon prompt. You should now be able to enter characters... at a maximum speed of about one character ever 4-5 seconds. This isn't a bit useful, but that really isn't the point, is it?


================
= TECH SUPPORT = 
================

TinyELF is free, and was written primarily for the author's own amusement and as an exercise in learning a little about Palm OS development. So as support goes, there's not much!

That said, please let me know if you find any bugs in TinyELF. While I'll also do what I can to answer questions that come my way, I'd encourage anyone with questions about basic ELF operation or 1802 programming to make use of the message board available from http://www.cosmacelf.com --- many very experienced 1802 programmers frequent the forum, but it's also a very friendly environment for people interested in learning the ins and outs of this interesting little microprocessor. 

And Tom Pittman's "Short Course in Programming", available on the same site with Tom's permission, is not to be missed: he starts by assuming almost no prior knowledge of computers, and winds up teaching advanced microprocessor concepts such as interrupt handling. While Dr. Pittman may be better known for his classic book on compilers ("The Art of Compiler Design: Theory and Practice"), his "Short Course" is remembered by many as their introduction to the world of microcomputing.

1802-based microcomputers might not have been very capable by today's standards... but they were educational, and great fun as well.

I hope you enjoy playing with TinyELF as much as I enjoyed writing it.

Have fun!

Dave Ruske
dave@ruske.net


===================
= VERSION HISTORY =
===================

*** 1.10 - June 8, 2003 ***

- Added keyboard support. To input ASCII into a TinyELF program with either an external keyboard or Graffiti, go to the Preferences dialog and select "ASCII"; to use the keyboard or Graffiti for hexadecimal input, select "Hex".

- Added bitmaps to the "Classic" skin to more accurately represent the hex displays on a real ELF computer.

- Fixed an interrupt related problem with the IDL instruction.

- Added a few new ELF programs to the supplied saved programs database.

- Modified help to include instructions about keyboard support and correct credit for the RsrcEdit program used in the construction of TinyELF.

- This ReadMe.txt file expanded to include notes about the ASCII keyboard and the sample programs provided in elfprog-1802.pdb.

- Updated copyright notice.


*** 1.00 - April 10, 2001 ***

- Fixed Pixie graphics to not shut down in Pause mode.

- Fixed the "Starship Animation" sample program image.

- Set focus to save name field when save dialog invoked.

- Made save name field auto-shift.

- Fixed stack imbalance which could occur while deleting a TinyELF program.

- Fixed color support so that TinyELF retains compatibility with OS2.0.

- Added tver resource so database browsing utilities correctly report the version.

- Added this file to the distribution.


*** 0.80Beta - April 2, 2001 ***

- First version seen by someone other than the developer.

